Runs
A run is a process that loads your model to memory when the simulation starts.
Runs are managed in the JS libraries by the Run adapter.
Run state
The run state consists of the model variable values. Updating a variable value changes the run state.
- Archived state: the variable values that are saved to the database.
- In-memory state: all the current variable values for the model loaded into memory.
Rituals
A ritual defines how Epicenter retrieves run state while performing operations like retrieving variables, updating metadata, or invoking model operations. All rituals prefer in-memory state when it is available and determine fallback behavior for runs that are not currently in memory.
For descriptions of rituals, see the RITUAL enum reference.
Run restore
When users reconnect, we load the model into memory again and restore the run to the point where the game was interrupted.
The two options for restoring a run:
- Replay: When replay is enabled, Epicenter records all state-changing operations on the model. In this case we replay the entire history of state changing commands to restore the run.
- Snapshot: The run snapshot consists of the current or latest values of all model variables. To use snapshot restore, you must save all necessary state variables to the database. Only available for models written in programming languages, such as Python or JavaScript.
If a history restore for your model takes a long time, it makes sense to restore from the snapshot.
To configure run restoration, update the restorations object in your model context file.
To restore a model run, use the restore() function of the run adapter.
For performance and capacity reasons, facilitator pages should not restore runs to memory. Instead they should query for runs to retrieve model variables from the database.
Run rewind
Rewinding a model run means going back a number of steps. To rewind a run, Epicenter restarts the model and replays all the step up to the one you are rewinding to. Hence, the application developers don't need to create a rewind function for their sim.
To rewind model runs create a rewind property in the restorations object in your model context file and use the rewind() function of the run adapter.
Recording a model run
To be able to replay a model run for a group, you record all HTTP calls in a group-specific log file. Each group exposes a flightRecorder property. Set the values in a group's flight recorder to enable and schedule a run recording.
Searching for runs
To search for runs that have a specific variable value, use the run adapter's query() function with the searchOptions.variables parameter.
For example, to display the runs for a group on a facilitator page, call the query() function as follows:
import { runAdapter } from 'epicenter-libs';
runAdapter.query('myModel.xlsx', {
groupName: "myGroupName"
});
Attaching worlds
The participants of a model run comprise a world. A single-player run doesn't need a world. However, a multiplayer run must be attached to a world.
It is a best practice to use worlds even if you only have single-player runs. Similarly, it is a best practice to use episodes even if you only need one. If you design your project without episodes and worlds and need them later, you will need to redesign the project.
Singular runs
A singular run has a well known runKey that is unique to the project. There can be only one singular run per project.
The singular run is scoped to a project which means it can hold project-level state and will exist as long as the project is not deleted.
Example use case
A singular run could be used to create a base case in a scenario where users may run the simulation many times and compare their results to the base case.
To manage singular runs, use the singular run functions of the Run adapter.
Sensitivity runs
A sensitivity run is a series of runs that Vensim can do with slight variable-value variations.
To learn more, read the Sensitivity Simulations article in Vensim help.